Crate insta

Source
Expand description

insta: a snapshot testing library for Rust

§What are snapshot tests

Snapshots tests (also sometimes called approval tests) are tests that assert values against a reference value (the snapshot). This is similar to how assert_eq! lets you compare a value against a reference value but unlike simple string assertions, snapshot tests let you test against complex values and come with comprehensive tools to review changes.

Snapshot tests are particularly useful if your reference values are very large or change often.

§What it looks like:

#[test]
fn test_hello_world() {
    insta::assert_debug_snapshot!(vec![1, 2, 3]);
}

Where are the snapshots stored? Right next to your test in a folder called snapshots as individual .snap files.

Got curious?

§Writing Tests

use insta::assert_debug_snapshot;

#[test]
fn test_snapshots() {
    assert_debug_snapshot!(vec![1, 2, 3]);
}

The recommended flow is to run the tests once, have them fail and check if the result is okay. By default, the new snapshots are stored next to the old ones with the extra .new extension. Once you are satisfied move the new files over. To simplify this workflow you can use cargo insta review (requires cargo-insta) which will let you interactively review them:

$ cargo test
$ cargo insta review

§Use Without cargo-insta

Note that cargo-insta is entirely optional. You can also just use insta directly from cargo test and control it via the INSTA_UPDATE environment variable — see Updating snapshots for details.

You can for instance first run the tests and not write and new snapshots, and if you like them run the tests again and update them:

INSTA_UPDATE=no cargo test
INSTA_UPDATE=always cargo test

§Assertion Macros

This crate exports multiple macros for snapshot testing:

The following macros require the use of serde::Serialize:

For macros that work with serde this crate also permits redacting of partial values. See redactions in the documentation for more information.

§Updating snapshots

During test runs snapshots will be updated according to the INSTA_UPDATE environment variable. The default is auto which will write snapshots for any failing tests into .snap.new files (if no CI is detected) so that cargo-insta can pick them up for review. Normally you don’t have to change this variable.

INSTA_UPDATE modes:

  • auto: the default. no for CI environments or new otherwise
  • new: writes snapshots for any failing tests into .snap.new files, pending review
  • always: writes snapshots for any failing tests into .snap files, bypassing review
  • unseen: always for previously unseen snapshots or new for existing snapshots
  • no: does not write to snapshot files at all; just runs tests
  • force: forcibly updates snapshot files, even if assertions pass

When new, auto or unseen is used, the cargo-insta command can be used to review the snapshots conveniently:

$ cargo insta review

“enter” or “a” accepts a new snapshot, “escape” or “r” rejects, “space” or “s” skips the snapshot for now.

For more information read the cargo insta docs.

§Inline Snapshots

Additionally snapshots can also be stored inline. In that case the format for the snapshot macros is assert_snapshot!(reference_value, @"snapshot"). The leading at sign (@) indicates that the following string is the reference value. On review, cargo-insta will update the string with the new value.

Example:

assert_snapshot!(2 + 2, @"");

Like with normal snapshots, an initial test failure will write the proposed value into a draft file (note that inline snapshots use .pending-snap files rather than .snap.new files). Running cargo insta review will review the proposed changes and update the source files on acceptance automatically.

§Features

The following features exist:

  • csv: enables CSV support (via serde)
  • json: enables JSON support (via serde)
  • ron: enables RON support (via serde)
  • toml: enables TOML support (via serde)
  • yaml: enables YAML support (via serde)
  • redactions: enables support for redactions
  • filters: enables support for filters
  • glob: enables support for globbing (glob!)
  • colors: enables color output (enabled by default)

For legacy reasons the json and yaml features are enabled by default in limited capacity. You will receive a deprecation warning if you are not opting into them but for now the macros will continue to function.

Enabling any of the serde based formats enables the hidden serde feature which gates some serde specific APIs such as Settings::set_info.

§Dependencies

insta tries to be light in dependencies but this is tricky to accomplish given what it tries to do. By default, it currently depends on serde for the assert_toml_snapshot! and assert_yaml_snapshot! macros. In the future this default dependencies will be removed. To already benefit from this optimization you can disable the default features and manually opt into what you want.

§Settings

There are some settings that can be changed on a per-thread (and thus per-test) basis. For more information see Settings.

Additionally, Insta will load a YAML config file with settings that change the behavior of insta between runs. It’s loaded from any of the following locations: .config/insta.yaml, insta.yaml and .insta.yaml from the workspace root. The following config options exist:

behavior:
  # also set by INSTA_REQUIRE_FULL_MATCH
  require_full_match: true/false
  # also set by INSTA_FORCE_PASS
  force_pass: true/false
  # also set by INSTA_OUTPUT
  output: "diff" | "summary" | "minimal" | "none"
  # also set by INSTA_UPDATE
  update: "auto" | "new" | "always" | "no" | "unseen" | "force"
  # also set by INSTA_GLOB_FAIL_FAST
  glob_fail_fast: true/false

# these are used by cargo insta test
test:
  # also set by INSTA_TEST_RUNNER
  runner: "auto" | "cargo-test" | "nextest"
  # whether to fallback to `cargo-test` if `nextest` is not available,
  # also set by INSTA_TEST_RUNNER_FALLBACK, default false
  test_runner_fallback: true/false
  # automatically assume --review was passed to cargo insta test
  auto_review: true/false
  # automatically assume --accept-unseen was passed to cargo insta test
  auto_accept_unseen: true/false

# these are used by cargo insta review
review:
  # also look for snapshots in ignored folders
  include_ignored: true / false
  # also look for snapshots in hidden folders
  include_hidden: true / false
  # show a warning if undiscovered (ignored or hidden) snapshots are found.
  # defaults to true but creates a performance hit.
  warn_undiscovered: true / false

§Optional: Faster Runs

Insta benefits from being compiled in release mode, even as dev dependency. It will compile slightly slower once, but use less memory, have faster diffs and just generally be more fun to use. To achieve that, opt insta and similar (the diffing library) into higher optimization in your Cargo.toml:

[profile.dev.package.insta]
opt-level = 3

[profile.dev.package.similar]
opt-level = 3

You can also disable the default features of insta which will cut down on the compile time a bit by removing some quality of life features.

Modules§

Macros§

Structs§

  • MetaData
    Snapshot metadata information.
  • Settings
    Configures how insta operates at test time.
  • Snapshot
    A helper to work with file snapshots.

Enums§

Functions§